<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>FileReadLine</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>FileReadLine</h1>

<p>Reads the specified line  from a file and stores the text in a <a href="../Variables.htm">variable</a>.</p>

<pre class="Syntax">FileReadLine, OutputVar, Filename, LineNum</pre>
<h3>Parameters</h3>
<dl>

  <dt>OutputVar</dt>
  <dd><p>The name of the <a href="../Variables.htm">variable</a> in which to store the retrieved text.</p></dd>

  <dt>Filename</dt>
  <dd><p>The name of the file to access, which is assumed to be in <a href="../Variables.htm#WorkingDir">%A_WorkingDir%</a> if an absolute path isn't specified. Windows and Unix formats are supported; that is, the file's lines may end in either carriage return and linefeed (`r`n) or just linefeed (`n).</p></dd>

  <dt>LineNum</dt>
  <dd><p>Which line to read (1 is the first, 2 the second, and so on). This can be an <a href="../Variables.htm#Expressions">expression</a>.</p>
    <p>If the specified line number is greater than the number of lines in the file, <a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 1 and <em>OutputVar</em> is not changed. This also happens when the specified line number is the last line in the file but that line is blank and does not end in a newline/CRLF.</p></dd>

</dl>

<h3>ErrorLevel</h3>
<p><span class="ver">[v1.1.04+]</span> This command is able to throw an exception on failure. For more information, see <a href="Catch.htm#RuntimeErrors">Runtime Errors</a>.</p>
<p><a href="../misc/ErrorLevel.htm">ErrorLevel</a> is set to 0 upon success. Otherwise it is set to 1 and the original contents of <em>OutputVar</em> are not changed.</p>
<p><a href="../Variables.htm#LastError">A_LastError</a> is set to the result of the operating system's GetLastError() function.</p>

<h3>Remarks</h3>
<p>It is strongly recommended to use this command only for small files, or in cases where only a single line of text is needed. To scan and process a large number of lines (one by one), use a <a href="LoopReadFile.htm">file-reading loop</a> for best performance. To read an entire file into a variable, use <a href="FileRead.htm">FileRead</a>.</p>
<p>Although any leading and trailing tabs and spaces present in the line will be written to <em>OutputVar</em>, the linefeed character (`n) at the end of the line will not. Tabs and spaces can be trimmed from both ends of any variable by assigning it to itself while <a href="AutoTrim.htm">AutoTrim</a> is on (the default). For example: <code>MyLine = %MyLine%</code>.</p>
<p>Lines  up to 65,534 characters long can be read. If the length of a line exceeds this, the remaining characters cannot be retrieved by this command (use <a href="FileRead.htm">FileRead</a> or a <a href="LoopReadFile.htm">file-reading loop</a> instead).</p>
<h3>Related</h3>
<p><a href="FileOpen.htm">FileOpen</a>/<a href="../objects/File.htm#ReadLine">File.ReadLine()</a>, <a href="FileRead.htm">FileRead</a>, <a href="FileAppend.htm">FileAppend</a>, <a href="LoopReadFile.htm">File-reading loop</a>, <a href="IniRead.htm">IniRead</a></p>
<h3>Example</h3>
<pre class="NoIndent">Loop
{
    FileReadLine, line, C:\My Documents\ContactList.txt, %A_Index%
    if ErrorLevel
        break
    MsgBox, 4, , Line #%A_Index% is &quot;%line%&quot;.  Continue?
    IfMsgBox, No
        return
}
MsgBox, The end of the file has been reached or there was a problem.
return</pre>

</body>
</html>
